home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / utils / file / findutil.001 / findutil~ / usr / info / find.info-1 next >
Encoding:
GNU Info File  |  1995-05-29  |  49.6 KB  |  1,582 lines
  1. This is Info file find.info, produced by Makeinfo-1.55 from the input
  2. file find.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Finding Files: (find).        Listing and operating on files
  6.                                 that match certain criteria.
  7. END-INFO-DIR-ENTRY
  8.  
  9.    This file documents the GNU utilities for finding files that match
  10. certain criteria and performing various operations on them.
  11.  
  12.    Copyright (C) 1994 Free Software Foundation, Inc.
  13.  
  14.    Permission is granted to make and distribute verbatim copies of this
  15. manual provided the copyright notice and this permission notice are
  16. preserved on all copies.
  17.  
  18.    Permission is granted to copy and distribute modified versions of
  19. this manual under the conditions for verbatim copying, provided that
  20. the entire resulting derived work is distributed under the terms of a
  21. permission notice identical to this one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that this permission notice may be stated in a
  26. translation approved by the Foundation.
  27.  
  28. 
  29. File: find.info,  Node: Top,  Next: Introduction,  Up: (dir)
  30.  
  31.    This file documents the GNU utilities for finding files that match
  32. certain criteria and performing various actions on them.  This is
  33. edition 1.1, for `find' version 4.1.
  34.  
  35. * Menu:
  36.  
  37. * Introduction::                Summary of the tasks this manual describes.
  38. * Finding Files::               Finding files that match certain criteria.
  39. * Actions::                     Doing things to files you have found.
  40. * Common Tasks::                Solutions to common real-world problems.
  41. * Databases::                   Maintaining file name databases.
  42. * File Permissions::            How to control access to files.
  43. * Reference::                   Summary of how to invoke the programs.
  44. * Primary Index::               The components of `find' expressions.
  45.  
  46. 
  47. File: find.info,  Node: Introduction,  Next: Finding Files,  Prev: Top,  Up: Top
  48.  
  49. Introduction
  50. ************
  51.  
  52.    This manual shows how to find files that meet criteria you specify,
  53. and how to perform various actions on the files that you find.  The
  54. principal programs that you use to perform these tasks are `find',
  55. `locate', and `xargs'.  Some of the examples in this manual use
  56. capabilities specific to the GNU versions of those programs.
  57.  
  58.    GNU `find' was originally written by Eric Decker, with enhancements
  59. by David MacKenzie, Jay Plett, and Tim Wood.  GNU `xargs' was
  60. originally written by Mike Rendell, with enhancements by David
  61. MacKenzie.  GNU `locate' and its associated utilities were originally
  62. written by James Woods, with enhancements by David MacKenzie.  The idea
  63. for `find -print0' and `xargs -0' came from Dan Bernstein.  Many other
  64. people have contributed bug fixes, small improvements, and helpful
  65. suggestions.  Thanks!
  66.  
  67.    Mail suggestions and bug reports for these programs to
  68. `bug-gnu-utils@prep.ai.mit.edu'.  Please include the version number,
  69. which you can get by running `find --version'.
  70.  
  71. * Menu:
  72.  
  73. * Scope::
  74. * Overview::
  75. * find Expressions::
  76.  
  77. 
  78. File: find.info,  Node: Scope,  Next: Overview,  Up: Introduction
  79.  
  80. Scope
  81. =====
  82.  
  83.    For brevity, the word "file" in this manual means a regular file, a
  84. directory, a symbolic link, or any other kind of node that has a
  85. directory entry.  A directory entry is also called a "file name".  A
  86. file name may contain some, all, or none of the directories in a path
  87. that leads to the file.  These are all examples of what this manual
  88. calls "file names":
  89.  
  90.      parser.c
  91.      README
  92.      ./budget/may-94.sc
  93.      fred/.cshrc
  94.      /usr/local/include/termcap.h
  95.  
  96.    A "directory tree" is a directory and the files it contains, all of
  97. its subdirectories and the files they contain, etc.  It can also be a
  98. single non-directory file.
  99.  
  100.    These programs enable you to find the files in one or more directory
  101. trees that:
  102.  
  103.    * have names that contain certain text or match a certain pattern;
  104.  
  105.    * are links to certain files;
  106.  
  107.    * were last used during a certain period of time;
  108.  
  109.    * are within a certain size range;
  110.  
  111.    * are of a certain type (regular file, directory, symbolic link,
  112.      etc.);
  113.  
  114.    * are owned by a certain user or group;
  115.  
  116.    * have certain access permissions;
  117.  
  118.    * contain text that matches a certain pattern;
  119.  
  120.    * are within a certain depth in the directory tree;
  121.  
  122.    * or some combination of the above.
  123.  
  124.    Once you have found the files you're looking for (or files that are
  125. potentially the ones you're looking for), you can do more to them than
  126. simply list their names.  You can get any combination of the files'
  127. attributes, or process the files in many ways, either individually or in
  128. groups of various sizes.  Actions that you might want to perform on the
  129. files you have found include, but are not limited to:
  130.  
  131.    * view or edit
  132.  
  133.    * store in an archive
  134.  
  135.    * remove or rename
  136.  
  137.    * change access permissions
  138.  
  139.    * classify into groups
  140.  
  141.    This manual describes how to perform each of those tasks, and more.
  142.  
  143. 
  144. File: find.info,  Node: Overview,  Next: find Expressions,  Prev: Scope,  Up: Introduction
  145.  
  146. Overview
  147. ========
  148.  
  149.    The principal programs used for making lists of files that match
  150. given criteria and running commands on them are `find', `locate', and
  151. `xargs'.  An additional command, `updatedb', is used by system
  152. administrators to create databases for `locate' to use.
  153.  
  154.    `find' searches for files in a directory hierarchy and prints
  155. information about the files it found.  It is run like this:
  156.  
  157.      find [FILE...] [EXPRESSION]
  158.  
  159. Here is a typical use of `find'.  This example prints the names of all
  160. files in the directory tree rooted in `/usr/src' whose name ends with
  161. `.c' and that are larger than 100 Kilobytes.
  162.      find /usr/src -name '*.c' -size +100k -print
  163.  
  164.    `locate' searches special file name databases for file names that
  165. match patterns.  The system administrator runs the `updatedb' program
  166. to create the databases.  `locate' is run like this:
  167.  
  168.      locate [OPTION...] PATTERN...
  169.  
  170. This example prints the names of all files in the default file name
  171. database whose name ends with `Makefile' or `makefile'.  Which file
  172. names are stored in the database depends on how the system
  173. administrator ran `updatedb'.
  174.      locate '*[Mm]akefile'
  175.  
  176.    The name `xargs', pronounced EX-args, means "combine arguments."
  177. `xargs' builds and executes command lines by gathering together
  178. arguments it reads on the standard input.  Most often, these arguments
  179. are lists of file names generated by `find'.  `xargs' is run like this:
  180.  
  181.      xargs [OPTION...] [COMMAND [INITIAL-ARGUMENTS]]
  182.  
  183. The following command searches the files listed in the file `file-list'
  184. and prints all of the lines in them that contain the word `typedef'.
  185.      xargs grep typedef < file-list
  186.  
  187. 
  188. File: find.info,  Node: find Expressions,  Prev: Overview,  Up: Introduction
  189.  
  190. `find' Expressions
  191. ==================
  192.  
  193.    The expression that `find' uses to select files consists of one or
  194. more "primaries", each of which is a separate command line argument to
  195. `find'.  `find' evaluates the expression each time it processes a file.
  196. An expression can contain any of the following types of primaries:
  197.  
  198. "options"
  199.      affect overall operation rather than the processing of a specific
  200.      file;
  201.  
  202. "tests"
  203.      return a true or false value, depending on the file's attributes;
  204.  
  205. "actions"
  206.      have side effects and return a true or false value; and
  207.  
  208. "operators"
  209.      connect the other arguments and affect when and whether they are
  210.      evaluated.
  211.  
  212.    You can omit the operator between two primaries; it defaults to
  213. `-and'.  *Note Combining Primaries With Operators::, for ways to
  214. connect primaries into more complex expressions.  If the expression
  215. contains no actions other than `-prune', `-print' is performed on all
  216. files for which the entire expression is true (*note Print File
  217. Name::.).
  218.  
  219.    Options take effect immediately, rather than being evaluated for each
  220. file when their place in the expression is reached.  Therefore, for
  221. clarity, it is best to place them at the beginning of the expression.
  222.  
  223.    Many of the primaries take arguments, which immediately follow them
  224. in the next command line argument to `find'.  Some arguments are file
  225. names, patterns, or other strings; others are numbers.  Numeric
  226. arguments can be specified as
  227.  
  228. `+N'
  229.      for greater than N,
  230.  
  231. `-N'
  232.      for less than N,
  233.  
  234. `N'
  235.      for exactly N.
  236.  
  237. 
  238. File: find.info,  Node: Finding Files,  Next: Actions,  Prev: Introduction,  Up: Top
  239.  
  240. Finding Files
  241. *************
  242.  
  243.    By default, `find' prints to the standard output the names of the
  244. files that match the given criteria.  *Note Actions::, for how to get
  245. more information about the matching files.
  246.  
  247. * Menu:
  248.  
  249. * Name::
  250. * Links::
  251. * Time::
  252. * Size::
  253. * Type::
  254. * Owner::
  255. * Permissions::
  256. * Contents::
  257. * Directories::
  258. * Filesystems::
  259. * Combining Primaries With Operators::
  260.  
  261. 
  262. File: find.info,  Node: Name,  Next: Links,  Up: Finding Files
  263.  
  264. Name
  265. ====
  266.  
  267.    Here are ways to search for files whose name matches a certain
  268. pattern.  *Note Shell Pattern Matching::, for a description of the
  269. PATTERN arguments to these tests.
  270.  
  271.    Each of these tests has a case-sensitive version and a
  272. case-insensitive version, whose name begins with `i'.  In a
  273. case-insensitive comparison, the patterns `fo*' and `F??' match the
  274. file names `Foo', `FOO', `foo', `fOo', etc.
  275.  
  276. * Menu:
  277.  
  278. * Base Name Patterns::
  279. * Full Name Patterns::
  280. * Fast Full Name Search::
  281. * Shell Pattern Matching::      Wildcards used by these programs.
  282.  
  283. 
  284. File: find.info,  Node: Base Name Patterns,  Next: Full Name Patterns,  Up: Name
  285.  
  286. Base Name Patterns
  287. ------------------
  288.  
  289.  - Test: -name PATTERN
  290.  - Test: -iname PATTERN
  291.      True if the base of the file name (the path with the leading
  292.      directories removed) matches shell pattern PATTERN.  For `-iname',
  293.      the match is case-insensitive.  To ignore a whole directory tree,
  294.      use `-prune' (*note Directories::.).  As an example, to find
  295.      Texinfo source files in `/usr/local/doc':
  296.  
  297.           find /usr/local/doc -name '*.texi'
  298.  
  299. 
  300. File: find.info,  Node: Full Name Patterns,  Next: Fast Full Name Search,  Prev: Base Name Patterns,  Up: Name
  301.  
  302. Full Name Patterns
  303. ------------------
  304.  
  305.  - Test: -path PATTERN
  306.  - Test: -ipath PATTERN
  307.      True if the entire file name, starting with the command line
  308.      argument under which the file was found, matches shell pattern
  309.      PATTERN.  For `-ipath', the match is case-insensitive.  To ignore
  310.      a whole directory tree, use `-prune' rather than checking every
  311.      file in the tree (*note Directories::.).
  312.  
  313.  - Test: -regex EXPR
  314.  - Test: -iregex EXPR
  315.      True if the entire file name matches regular expression EXPR.
  316.      This is a match on the whole path, not a search.  For example, to
  317.      match a file named `./fubar3', you can use the regular expression
  318.      `.*bar.' or `.*b.*3', but not `b.*r3'.  *Note Syntax of Regular
  319.      Expressions: (emacs)Regexps, for a description of the syntax of
  320.      regular expressions.  For `-iregex', the match is case-insensitive.
  321.  
  322. 
  323. File: find.info,  Node: Fast Full Name Search,  Next: Shell Pattern Matching,  Prev: Full Name Patterns,  Up: Name
  324.  
  325. Fast Full Name Search
  326. ---------------------
  327.  
  328.    To search for files by name without having to actually scan the
  329. directories on the disk (which can be slow), you can use the `locate'
  330. program.  For each shell pattern you give it, `locate' searches one or
  331. more databases of file names and displays the file names that contain
  332. the pattern.  *Note Shell Pattern Matching::, for details about shell
  333. patterns.
  334.  
  335.    If a pattern is a plain string--it contains no
  336. metacharacters--`locate' displays all file names in the database that
  337. contain that string.  If a pattern contains metacharacters, `locate'
  338. only displays file names that match the pattern exactly.  As a result,
  339. patterns that contain metacharacters should usually begin with a `*',
  340. and will most often end with one as well.  The exceptions are patterns
  341. that are intended to explicitly match the beginning or end of a file
  342. name.
  343.  
  344.    The command
  345.      locate PATTERN
  346.  
  347.    is almost equivalent to
  348.      find DIRECTORIES -name PATTERN
  349.  
  350.    where DIRECTORIES are the directories for which the file name
  351. databases contain information.  The differences are that the `locate'
  352. information might be out of date, and that `locate' handles wildcards
  353. in the pattern slightly differently than `find' (*note Shell Pattern
  354. Matching::.).
  355.  
  356.    The file name databases contain lists of files that were on the
  357. system when the databases were last updated.  The system administrator
  358. can choose the file name of the default database, the frequency with
  359. which the databases are updated, and the directories for which they
  360. contain entries.
  361.  
  362.    Here is how to select which file name databases `locate' searches.
  363. The default is system-dependent.
  364.  
  365. `--database=PATH'
  366. `-d PATH'
  367.      Instead of searching the default file name database, search the
  368.      file name databases in PATH, which is a colon-separated list of
  369.      database file names.  You can also use the environment variable
  370.      `LOCATE_PATH' to set the list of database files to search.  The
  371.      option overrides the environment variable if both are used.
  372.  
  373. 
  374. File: find.info,  Node: Shell Pattern Matching,  Prev: Fast Full Name Search,  Up: Name
  375.  
  376. Shell Pattern Matching
  377. ----------------------
  378.  
  379.    `find' and `locate' can compare file names, or parts of file names,
  380. to shell patterns.  A "shell pattern" is a string that may contain the
  381. following special characters, which are known as "wildcards" or
  382. "metacharacters".
  383.  
  384.    You must quote patterns that contain metacharacters to prevent the
  385. shell from expanding them itself.  Double and single quotes both work;
  386. so does escaping with a backslash.
  387.  
  388. `*'
  389.      Matches any zero or more characters.
  390.  
  391. `?'
  392.      Matches any one character.
  393.  
  394. `[STRING]'
  395.      Matches exactly one character that is a member of the string
  396.      STRING.  This is called a "character class".  As a shorthand,
  397.      STRING may contain ranges, which consist of two characters with a
  398.      dash between them.  For example, the class `[a-z0-9_]' matches a
  399.      lowercase letter, a number, or an underscore.  You can negate a
  400.      class by placing a `!' or `^' immediately after the opening
  401.      bracket.  Thus, `[^A-Z@]' matches any character except an
  402.      uppercase letter or an at sign.
  403.  
  404. `\'
  405.      Removes the special meaning of the character that follows it.  This
  406.      works even in character classes.
  407.  
  408.    In the `find' tests that do shell pattern matching (`-name',
  409. `-path', etc.), wildcards in the pattern do not match a `.' at the
  410. beginning of a file name.  This is not the case for `locate'.  Thus,
  411. `find -name '*macs'' does not match a file named `.emacs', but `locate
  412. '*macs'' does.
  413.  
  414.    Slash characters have no special significance in the shell pattern
  415. matching that `find' and `locate' do, unlike in the shell, in which
  416. wildcards do not match them.  Therefore, a pattern `foo*bar' can match
  417. a file name `foo3/bar', and a pattern `./sr*sc' can match a file name
  418. `./src/misc'.
  419.  
  420. 
  421. File: find.info,  Node: Links,  Next: Time,  Prev: Name,  Up: Finding Files
  422.  
  423. Links
  424. =====
  425.  
  426.    There are two ways that files can be linked together.  "Symbolic
  427. links" are a special type of file whose contents are a portion of the
  428. name of another file.  "Hard links" are multiple directory entries for
  429. one file; the file names all have the same index node ("inode") number
  430. on the disk.
  431.  
  432. * Menu:
  433.  
  434. * Symbolic Links::
  435. * Hard Links::
  436.  
  437. 
  438. File: find.info,  Node: Symbolic Links,  Next: Hard Links,  Up: Links
  439.  
  440. Symbolic Links
  441. --------------
  442.  
  443.  - Test: -lname PATTERN
  444.  - Test: -ilname PATTERN
  445.      True if the file is a symbolic link whose contents match shell
  446.      pattern PATTERN.  For `-ilname', the match is case-insensitive.
  447.      *Note Shell Pattern Matching::, for details about the PATTERN
  448.      argument.  So, to list any symbolic links to `sysdep.c' in the
  449.      current directory and its subdirectories, you can do:
  450.  
  451.           find . -lname '*sysdep.c'
  452.  
  453.  - Option: -follow
  454.      Dereference symbolic links.  The following differences in behavior
  455.      occur when this option is given:
  456.  
  457.         * `find' follows symbolic links to directories when searching
  458.           directory trees.
  459.  
  460.         * `-lname' and `-ilname' always return false.
  461.  
  462.         * `-type' reports the types of the files that symbolic links
  463.           point to.
  464.  
  465.         * Implies `-noleaf' (*note Directories::.).
  466.  
  467. 
  468. File: find.info,  Node: Hard Links,  Prev: Symbolic Links,  Up: Links
  469.  
  470. Hard Links
  471. ----------
  472.  
  473.    To find hard links, first get the inode number of the file whose
  474. links you want to find.  You can learn a file's inode number and the
  475. number of links to it by running `ls -i' or `find -ls'.  If the file has
  476. more than one link, you can search for the other links by passing that
  477. inode number to `-inum'.  Add the `-xdev' option if you are starting
  478. the search at a directory that has other filesystems mounted on it,
  479. such as `/usr' on many systems.  Doing this saves needless searching,
  480. since hard links to a file must be on the same filesystem.  *Note
  481. Filesystems::.
  482.  
  483.  - Test: -inum N
  484.      File has inode number N.
  485.  
  486.    You can also search for files that have a certain number of links,
  487. with `-links'.  Directories normally have at least two hard links; their
  488. `.' entry is the second one.  If they have subdirectories, each of
  489. those also has a hard link called `..' to its parent directory.
  490.  
  491.  - Test: -links N
  492.      File has N hard links.
  493.  
  494. 
  495. File: find.info,  Node: Time,  Next: Size,  Prev: Links,  Up: Finding Files
  496.  
  497. Time
  498. ====
  499.  
  500.    Each file has three time stamps, which record the last time that
  501. certain operations were performed on the file:
  502.  
  503.   1. access (read the file's contents)
  504.  
  505.   2. change the status (modify the file or its attributes)
  506.  
  507.   3. modify (change the file's contents)
  508.  
  509.    You can search for files whose time stamps are within a certain age
  510. range, or compare them to other time stamps.
  511.  
  512. * Menu:
  513.  
  514. * Age Ranges::
  515. * Comparing Timestamps::
  516.  
  517. 
  518. File: find.info,  Node: Age Ranges,  Next: Comparing Timestamps,  Up: Time
  519.  
  520. Age Ranges
  521. ----------
  522.  
  523.    These tests are mainly useful with ranges (`+N' and `-N').
  524.  
  525.  - Test: -atime N
  526.  - Test: -ctime N
  527.  - Test: -mtime N
  528.      True if the file was last accessed (or its status changed, or it
  529.      was modified) N*24 hours ago.
  530.  
  531.  - Test: -amin N
  532.  - Test: -cmin N
  533.  - Test: -mmin N
  534.      True if the file was last accessed (or its status changed, or it
  535.      was modified) N minutes ago.  These tests provide finer
  536.      granularity of measurement than `-atime' et al.  For example, to
  537.      list files in `/u/bill' that were last read from 2 to 6 hours ago:
  538.  
  539.           find /u/bill -amin +2 -amin -6
  540.  
  541.  - Option: -daystart
  542.      Measure times from the beginning of today rather than from 24
  543.      hours ago.  So, to list the regular files in your home directory
  544.      that were modified yesterday, do
  545.  
  546.           find ~ -daystart -type f -mtime 1
  547.  
  548. 
  549. File: find.info,  Node: Comparing Timestamps,  Prev: Age Ranges,  Up: Time
  550.  
  551. Comparing Timestamps
  552. --------------------
  553.  
  554.    As an alternative to comparing timestamps to the current time, you
  555. can compare them to another file's timestamp.  That file's timestamp
  556. could be updated by another program when some event occurs.  Or you
  557. could set it to a particular fixed date using the `touch' command.  For
  558. example, to list files in `/usr' modified after February 1 of the
  559. current year:
  560.  
  561.      touch -t 02010000 /tmp/stamp$$
  562.      find /usr -newer /tmp/stamp$$
  563.      rm -f /tmp/stamp$$
  564.  
  565.  - Test: -anewer FILE
  566.  - Test: -cnewer FILE
  567.  - Test: -newer FILE
  568.      True if the file was last accessed (or its status changed, or it
  569.      was modified) more recently than FILE was modified.  These tests
  570.      are affected by `-follow' only if `-follow' comes before them on
  571.      the command line.  *Note Symbolic Links::, for more information on
  572.      `-follow'.  As an example, to list any files modified since
  573.      `/bin/sh' was last modified:
  574.  
  575.           find . -newer /bin/sh
  576.  
  577.  - Test: -used N
  578.      True if the file was last accessed N days after its status was
  579.      last changed.  Useful for finding files that are not being used,
  580.      and could perhaps be archived or removed to save disk space.
  581.  
  582. 
  583. File: find.info,  Node: Size,  Next: Type,  Prev: Time,  Up: Finding Files
  584.  
  585. Size
  586. ====
  587.  
  588.  - Test: -size N[BCKW]
  589.      True if the file uses N units of space, rounding up.  The units
  590.      are 512-byte blocks by default, but they can be changed by adding a
  591.      one-character suffix to N:
  592.  
  593.     `b'
  594.           512-byte blocks
  595.  
  596.     `c'
  597.           bytes
  598.  
  599.     `k'
  600.           kilobytes (1024 bytes)
  601.  
  602.     `w'
  603.           2-byte words
  604.  
  605.      The size does not count indirect blocks, but it does count blocks
  606.      in sparse files that are not actually allocated.
  607.  
  608.  - Test: -empty
  609.      True if the file is empty and is either a regular file or a
  610.      directory.  This might make it a good candidate for deletion.
  611.      This test is useful with `-depth' (*note Directories::.) and
  612.      `-exec rm -rf '{}' ';'' (*note Single File::.).
  613.  
  614. 
  615. File: find.info,  Node: Type,  Next: Owner,  Prev: Size,  Up: Finding Files
  616.  
  617. Type
  618. ====
  619.  
  620.  - Test: -type C
  621.      True if the file is of type C:
  622.  
  623.     `b'
  624.           block (buffered) special
  625.  
  626.     `c'
  627.           character (unbuffered) special
  628.  
  629.     `d'
  630.           directory
  631.  
  632.     `p'
  633.           named pipe (FIFO)
  634.  
  635.     `f'
  636.           regular file
  637.  
  638.     `l'
  639.           symbolic link
  640.  
  641.     `s'
  642.           socket
  643.  
  644.  - Test: -xtype C
  645.      The same as `-type' unless the file is a symbolic link.  For
  646.      symbolic links: if `-follow' has not been given, true if the file
  647.      is a link to a file of type C; if `-follow' has been given, true
  648.      if C is `l'.  In other words, for symbolic links, `-xtype' checks
  649.      the type of the file that `-type' does not check.  *Note Symbolic
  650.      Links::, for more information on `-follow'.
  651.  
  652. 
  653. File: find.info,  Node: Owner,  Next: Permissions,  Prev: Type,  Up: Finding Files
  654.  
  655. Owner
  656. =====
  657.  
  658.  - Test: -user UNAME
  659.  - Test: -group GNAME
  660.      True if the file is owned by user UNAME (belongs to group GNAME).
  661.      A numeric ID is allowed.
  662.  
  663.  - Test: -uid N
  664.  - Test: -gid N
  665.      True if the file's numeric user ID (group ID) is N.  These tests
  666.      support ranges (`+N' and `-N'), unlike `-user' and `-group'.
  667.  
  668.  - Test: -nouser
  669.  - Test: -nogroup
  670.      True if no user corresponds to the file's numeric user ID (no group
  671.      corresponds to the numeric group ID).  These cases usually mean
  672.      that the files belonged to users who have since been removed from
  673.      the system.  You probably should change the ownership of such
  674.      files to an existing user or group, using the `chown' or `chgrp'
  675.      program.
  676.  
  677. 
  678. File: find.info,  Node: Permissions,  Next: Contents,  Prev: Owner,  Up: Finding Files
  679.  
  680. Permissions
  681. ===========
  682.  
  683.    *Note File Permissions::, for information on how file permissions are
  684. structured and how to specify them.
  685.  
  686.  - Test: -perm MODE
  687.      True if the file's permissions are exactly MODE (which can be
  688.      numeric or symbolic).  Symbolic modes use mode 0 as a point of
  689.      departure.  If MODE starts with `-', true if *all* of the
  690.      permissions set in MODE are set for the file; permissions not set
  691.      in MODE are ignored.  If MODE starts with `+', true if *any* of
  692.      the permissions set in MODE are set for the file; permissions not
  693.      set in MODE are ignored.
  694.  
  695. 
  696. File: find.info,  Node: Contents,  Next: Directories,  Prev: Permissions,  Up: Finding Files
  697.  
  698. Contents
  699. ========
  700.  
  701.    To search for files based on their contents, you can use the `grep'
  702. program.  For example, to find out which C source files in the current
  703. directory contain the string `thing', you can do:
  704.  
  705.      grep -l thing *.[ch]
  706.  
  707.    If you also want to search for the string in files in subdirectories,
  708. you can combine `grep' with `find' and `xargs', like this:
  709.  
  710.      find . -name '*.[ch]' | xargs grep -l thing
  711.  
  712.    The `-l' option causes `grep' to print only the names of files that
  713. contain the string, rather than the lines that contain it.  The string
  714. argument (`thing') is actually a regular expression, so it can contain
  715. metacharacters.  This method can be refined a little by using the `-r'
  716. option to make `xargs' not run `grep' if `find' produces no output, and
  717. using the `find' action `-print0' and the `xargs' option `-0' to avoid
  718. misinterpreting files whose names contain spaces:
  719.  
  720.      find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing
  721.  
  722.    For a fuller treatment of finding files whose contents match a
  723. pattern, see the manual page for `grep'.
  724.  
  725. 
  726. File: find.info,  Node: Directories,  Next: Filesystems,  Prev: Contents,  Up: Finding Files
  727.  
  728. Directories
  729. ===========
  730.  
  731.    Here is how to control which directories `find' searches, and how it
  732. searches them.  These two options allow you to process a horizontal
  733. slice of a directory tree.
  734.  
  735.  - Option: -maxdepth LEVELS
  736.      Descend at most LEVELS (a non-negative integer) levels of
  737.      directories below the command line arguments.  `-maxdepth 0' means
  738.      only apply the tests and actions to the command line arguments.
  739.  
  740.  - Option: -mindepth LEVELS
  741.      Do not apply any tests or actions at levels less than LEVELS (a
  742.      non-negative integer).  `-mindepth 1' means process all files
  743.      except the command line arguments.
  744.  
  745.  - Option: -depth
  746.      Process each directory's contents before the directory itself.
  747.      Doing this is a good idea when producing lists of files to archive
  748.      with `cpio' or `tar'.  If a directory does not have write
  749.      permission for its owner, its contents can still be restored from
  750.      the archive since the directory's permissions are restored after
  751.      its contents.
  752.  
  753.  - Action: -prune
  754.      If `-depth' is not given, true; do not descend the current
  755.      directory.  If `-depth' is given, false; no effect.  `-prune' only
  756.      affects tests and actions that come after it in the expression, not
  757.      those that come before.
  758.  
  759.      For example, to skip the directory `src/emacs' and all files and
  760.      directories under it, and print the names of the other files found:
  761.  
  762.           find . -path './src/emacs' -prune -o -print
  763.  
  764.  - Option: -noleaf
  765.      Do not optimize by assuming that directories contain 2 fewer
  766.      subdirectories than their hard link count.  This option is needed
  767.      when searching filesystems that do not follow the Unix
  768.      directory-link convention, such as CD-ROM or MS-DOS filesystems or
  769.      AFS volume mount points.  Each directory on a normal Unix
  770.      filesystem has at least 2 hard links: its name and its `.'  entry.
  771.      Additionally, its subdirectories (if any) each have a `..'  entry
  772.      linked to that directory.  When `find' is examining a directory,
  773.      after it has statted 2 fewer subdirectories than the directory's
  774.      link count, it knows that the rest of the entries in the directory
  775.      are non-directories ("leaf" files in the directory tree).  If only
  776.      the files' names need to be examined, there is no need to stat
  777.      them; this gives a significant increase in search speed.
  778.  
  779. 
  780. File: find.info,  Node: Filesystems,  Next: Combining Primaries With Operators,  Prev: Directories,  Up: Finding Files
  781.  
  782. Filesystems
  783. ===========
  784.  
  785.    A "filesystem" is a section of a disk, either on the local host or
  786. mounted from a remote host over a network.  Searching network
  787. filesystems can be slow, so it is common to make `find' avoid them.
  788.  
  789.    There are two ways to avoid searching certain filesystems.  One way
  790. is to tell `find' to only search one filesystem:
  791.  
  792.  - Option: -xdev
  793.  - Option: -mount
  794.      Don't descend directories on other filesystems.  These options are
  795.      synonyms.
  796.  
  797.    The other way is to check the type of filesystem each file is on, and
  798. not descend directories that are on undesirable filesystem types:
  799.  
  800.  - Test: -fstype TYPE
  801.      True if the file is on a filesystem of type TYPE.  The valid
  802.      filesystem types vary among different versions of Unix; an
  803.      incomplete list of filesystem types that are accepted on some
  804.      version of Unix or another is:
  805.           ufs 4.2 4.3 nfs tmp mfs S51K S52K
  806.      You can use `-printf' with the `%F' directive to see the types of
  807.      your filesystems.  *Note Print File Information::.  `-fstype' is
  808.      usually used with `-prune' to avoid searching remote filesystems
  809.      (*note Directories::.).
  810.  
  811. 
  812. File: find.info,  Node: Combining Primaries With Operators,  Prev: Filesystems,  Up: Finding Files
  813.  
  814. Combining Primaries With Operators
  815. ==================================
  816.  
  817.    Operators build a complex expression from tests and actions.  The
  818. operators are, in order of decreasing precedence:
  819.  
  820. `( EXPR )'
  821.      Force precedence.  True if EXPR is true.
  822.  
  823. `! EXPR'
  824. `-not EXPR'
  825.      True if EXPR is false.
  826.  
  827. `EXPR1 EXPR2'
  828. `EXPR1 -a EXPR2'
  829. `EXPR1 -and EXPR2'
  830.      And; EXPR2 is not evaluated if EXPR1 is false.
  831.  
  832. `EXPR1 -o EXPR2'
  833. `EXPR1 -or EXPR2'
  834.      Or; EXPR2 is not evaluated if EXPR1 is true.
  835.  
  836. `EXPR1 , EXPR2'
  837.      List; both EXPR1 and EXPR2 are always evaluated.  True if EXPR2 is
  838.      true.  The value of EXPR1 is discarded.  This operator lets you do
  839.      multiple independent operations on one traversal, without
  840.      depending on whether other operations succeeded.
  841.  
  842.    `find' searches the directory tree rooted at each file name by
  843. evaluating the expression from left to right, according to the rules of
  844. precedence, until the outcome is known (the left hand side is false for
  845. `-and', true for `-or'), at which point `find' moves on to the next
  846. file name.
  847.  
  848.    There are two other tests that can be useful in complex expressions:
  849.  
  850.  - Test: -true
  851.      Always true.
  852.  
  853.  - Test: -false
  854.      Always false.
  855.  
  856. 
  857. File: find.info,  Node: Actions,  Next: Common Tasks,  Prev: Finding Files,  Up: Top
  858.  
  859. Actions
  860. *******
  861.  
  862.    There are several ways you can print information about the files that
  863. match the criteria you gave in the `find' expression.  You can print
  864. the information either to the standard output or to a file that you
  865. name.  You can also execute commands that have the file names as
  866. arguments.  You can use those commands as further filters to select
  867. files.
  868.  
  869. * Menu:
  870.  
  871. * Print File Name::
  872. * Print File Information::
  873. * Run Commands::
  874. * Adding Tests::
  875.  
  876. 
  877. File: find.info,  Node: Print File Name,  Next: Print File Information,  Up: Actions
  878.  
  879. Print File Name
  880. ===============
  881.  
  882.  - Action: -print
  883.      True; print the full file name on the standard output, followed by
  884.      a newline.
  885.  
  886.  - Action: -fprint FILE
  887.      True; print the full file name into file FILE, followed by a
  888.      newline.  If FILE does not exist when `find' is run, it is
  889.      created; if it does exist, it is truncated to 0 bytes.  The file
  890.      names `/dev/stdout' and `/dev/stderr' are handled specially; they
  891.      refer to the standard output and standard error output,
  892.      respectively.
  893.  
  894. 
  895. File: find.info,  Node: Print File Information,  Next: Run Commands,  Prev: Print File Name,  Up: Actions
  896.  
  897. Print File Information
  898. ======================
  899.  
  900.  - Action: -ls
  901.      True; list the current file in `ls -dils' format on the standard
  902.      output.  The output looks like this:
  903.  
  904.           204744   17 -rw-r--r--   1 djm      staff       17337 Nov  2  1992 ./lwall-quotes
  905.  
  906.      The fields are:
  907.  
  908.        1. The inode number of the file.  *Note Hard Links::, for how to
  909.           find files based on their inode number.
  910.  
  911.        2. the number of blocks in the file.  The block counts are of 1K
  912.           blocks, unless the environment variable `POSIXLY_CORRECT' is
  913.           set, in which case 512-byte blocks are used.  *Note Size::,
  914.           for how to find files based on their size.
  915.  
  916.        3. The file's type and permissions.  The type is shown as a dash
  917.           for a regular file; for other file types, a letter like for
  918.           `-type' is used (*note Type::.).  The permissions are read,
  919.           write, and execute for the file's owner, its group, and other
  920.           users, respectively; a dash means the permission is not
  921.           granted.  *Note File Permissions::, for more details about
  922.           file permissions.  *Note Permissions::, for how to find files
  923.           based on their permissions.
  924.  
  925.        4. The number of hard links to the file.
  926.  
  927.        5. The user who owns the file.
  928.  
  929.        6. The file's group.
  930.  
  931.        7. The file's size in bytes.
  932.  
  933.        8. The date the file was last modified.
  934.  
  935.        9. The file's name.  `-ls' quotes non-printable characters in
  936.           the file names using C-like backslash escapes.
  937.  
  938.  - Action: -fls FILE
  939.      True; like `-ls' but write to FILE like `-fprint' (*note Print
  940.      File Name::.).
  941.  
  942.  - Action: -printf FORMAT
  943.      True; print FORMAT on the standard output, interpreting `\'
  944.      escapes and `%' directives.  Field widths and precisions can be
  945.      specified as with the `printf' C function.  Unlike `-print',
  946.      `-printf' does not add a newline at the end of the string.
  947.  
  948.  - Action: -fprintf FILE FORMAT
  949.      True; like `-printf' but write to FILE like `-fprint' (*note Print
  950.      File Name::.).
  951.  
  952. * Menu:
  953.  
  954. * Escapes::
  955. * Format Directives::
  956. * Time Formats::
  957.  
  958. 
  959. File: find.info,  Node: Escapes,  Next: Format Directives,  Up: Print File Information
  960.  
  961. Escapes
  962. -------
  963.  
  964.    The escapes that `-printf' and `-fprintf' recognize are:
  965.  
  966. `\a'
  967.      Alarm bell.
  968.  
  969. `\b'
  970.      Backspace.
  971.  
  972. `\c'
  973.      Stop printing from this format immediately and flush the output.
  974.  
  975. `\f'
  976.      Form feed.
  977.  
  978. `\n'
  979.      Newline.
  980.  
  981. `\r'
  982.      Carriage return.
  983.  
  984. `\t'
  985.      Horizontal tab.
  986.  
  987. `\v'
  988.      Vertical tab.
  989.  
  990. `\\'
  991.      A literal backslash (`\').
  992.  
  993.    A `\' character followed by any other character is treated as an
  994. ordinary character, so they both are printed, and a warning message is
  995. printed to the standard error output (because it was probably a typo).
  996.  
  997. 
  998. File: find.info,  Node: Format Directives,  Next: Time Formats,  Prev: Escapes,  Up: Print File Information
  999.  
  1000. Format Directives
  1001. -----------------
  1002.  
  1003.    `-printf' and `-fprintf' support the following format directives to
  1004. print information about the file being processed.  Unlike the C
  1005. `printf' function, they do not support field width specifiers.
  1006.  
  1007.    `%%' is a literal percent sign.  A `%' character followed by any
  1008. other character is discarded (but the other character is printed), and
  1009. a warning message is printed to the standard error output (because it
  1010. was probably a typo).
  1011.  
  1012. * Menu:
  1013.  
  1014. * Name Directives::
  1015. * Ownership Directives::
  1016. * Size Directives::
  1017. * Location Directives::
  1018. * Time Directives::
  1019.  
  1020. 
  1021. File: find.info,  Node: Name Directives,  Next: Ownership Directives,  Up: Format Directives
  1022.  
  1023. Name Directives
  1024. ...............
  1025.  
  1026. `%p'
  1027.      File's name.
  1028.  
  1029. `%f'
  1030.      File's name with any leading directories removed (only the last
  1031.      element).
  1032.  
  1033. `%h'
  1034.      Leading directories of file's name (all but the last element and
  1035.      the slash before it).
  1036.  
  1037. `%P'
  1038.      File's name with the name of the command line argument under which
  1039.      it was found removed from the beginning.
  1040.  
  1041. `%H'
  1042.      Command line argument under which file was found.
  1043.  
  1044. 
  1045. File: find.info,  Node: Ownership Directives,  Next: Size Directives,  Prev: Name Directives,  Up: Format Directives
  1046.  
  1047. Ownership Directives
  1048. ....................
  1049.  
  1050. `%g'
  1051.      File's group name, or numeric group ID if the group has no name.
  1052.  
  1053. `%G'
  1054.      File's numeric group ID.
  1055.  
  1056. `%u'
  1057.      File's user name, or numeric user ID if the user has no name.
  1058.  
  1059. `%U'
  1060.      File's numeric user ID.
  1061.  
  1062. `%m'
  1063.      File's permissions (in octal).
  1064.  
  1065. 
  1066. File: find.info,  Node: Size Directives,  Next: Location Directives,  Prev: Ownership Directives,  Up: Format Directives
  1067.  
  1068. Size Directives
  1069. ...............
  1070.  
  1071. `%k'
  1072.      File's size in 1K blocks (rounded up).
  1073.  
  1074. `%b'
  1075.      File's size in 512-byte blocks (rounded up).
  1076.  
  1077. `%s'
  1078.      File's size in bytes.
  1079.  
  1080. 
  1081. File: find.info,  Node: Location Directives,  Next: Time Directives,  Prev: Size Directives,  Up: Format Directives
  1082.  
  1083. Location Directives
  1084. ...................
  1085.  
  1086. `%d'
  1087.      File's depth in the directory tree; files named on the command line
  1088.      have a depth of 0.
  1089.  
  1090. `%F'
  1091.      Type of the filesystem the file is on; this value can be used for
  1092.      `-fstype' (*note Directories::.).
  1093.  
  1094. `%l'
  1095.      Object of symbolic link (empty string if file is not a symbolic
  1096.      link).
  1097.  
  1098. `%i'
  1099.      File's inode number (in decimal).
  1100.  
  1101. `%n'
  1102.      Number of hard links to file.
  1103.  
  1104. 
  1105. File: find.info,  Node: Time Directives,  Prev: Location Directives,  Up: Format Directives
  1106.  
  1107. Time Directives
  1108. ...............
  1109.  
  1110.    Some of these directives use the C `ctime' function.  Its output
  1111. depends on the current locale, but it typically looks like
  1112.  
  1113.      Wed Nov  2 00:42:36 1994
  1114.  
  1115. `%a'
  1116.      File's last access time in the format returned by the C `ctime'
  1117.      function.
  1118.  
  1119. `%AK'
  1120.      File's last access time in the format specified by K (*note Time
  1121.      Formats::.).
  1122.  
  1123. `%c'
  1124.      File's last status change time in the format returned by the C
  1125.      `ctime' function.
  1126.  
  1127. `%CK'
  1128.      File's last status change time in the format specified by K (*note
  1129.      Time Formats::.).
  1130.  
  1131. `%t'
  1132.      File's last modification time in the format returned by the C
  1133.      `ctime' function.
  1134.  
  1135. `%TK'
  1136.      File's last modification time in the format specified by K (*note
  1137.      Time Formats::.).
  1138.  
  1139. 
  1140. File: find.info,  Node: Time Formats,  Prev: Format Directives,  Up: Print File Information
  1141.  
  1142. Time Formats
  1143. ------------
  1144.  
  1145.    Below are the formats for the directives `%A', `%C', and `%T', which
  1146. print the file's timestamps.  Some of these formats might not be
  1147. available on all systems, due to differences in the C `strftime'
  1148. function between systems.
  1149.  
  1150. * Menu:
  1151.  
  1152. * Time Components::
  1153. * Date Components::
  1154. * Combined Time Formats::
  1155.  
  1156. 
  1157. File: find.info,  Node: Time Components,  Next: Date Components,  Up: Time Formats
  1158.  
  1159. Time Components
  1160. ...............
  1161.  
  1162.    The following format directives print single components of the time.
  1163.  
  1164. `H'
  1165.      hour (00..23)
  1166.  
  1167. `I'
  1168.      hour (01..12)
  1169.  
  1170. `k'
  1171.      hour ( 0..23)
  1172.  
  1173. `l'
  1174.      hour ( 1..12)
  1175.  
  1176. `p'
  1177.      locale's AM or PM
  1178.  
  1179. `Z'
  1180.      time zone (e.g., EDT), or nothing if no time zone is determinable
  1181.  
  1182. `M'
  1183.      minute (00..59)
  1184.  
  1185. `S'
  1186.      second (00..61)
  1187.  
  1188. `@'
  1189.      seconds since Jan. 1, 1970, 00:00 GMT.
  1190.  
  1191. 
  1192. File: find.info,  Node: Date Components,  Next: Combined Time Formats,  Prev: Time Components,  Up: Time Formats
  1193.  
  1194. Date Components
  1195. ...............
  1196.  
  1197.    The following format directives print single components of the date.
  1198.  
  1199. `a'
  1200.      locale's abbreviated weekday name (Sun..Sat)
  1201.  
  1202. `A'
  1203.      locale's full weekday name, variable length (Sunday..Saturday)
  1204.  
  1205. `b'
  1206. `h'
  1207.      locale's abbreviated month name (Jan..Dec)
  1208.  
  1209. `B'
  1210.      locale's full month name, variable length (January..December)
  1211.  
  1212. `m'
  1213.      month (01..12)
  1214.  
  1215. `d'
  1216.      day of month (01..31)
  1217.  
  1218. `w'
  1219.      day of week (0..6)
  1220.  
  1221. `j'
  1222.      day of year (001..366)
  1223.  
  1224. `U'
  1225.      week number of year with Sunday as first day of week (00..53)
  1226.  
  1227. `W'
  1228.      week number of year with Monday as first day of week (00..53)
  1229.  
  1230. `Y'
  1231.      year (1970...)
  1232.  
  1233. `y'
  1234.      last two digits of year (00..99)
  1235.  
  1236. 
  1237. File: find.info,  Node: Combined Time Formats,  Prev: Date Components,  Up: Time Formats
  1238.  
  1239. Combined Time Formats
  1240. .....................
  1241.  
  1242.    The following format directives print combinations of time and date
  1243. components.
  1244.  
  1245. `r'
  1246.      time, 12-hour (hh:mm:ss [AP]M)
  1247.  
  1248. `T'
  1249.      time, 24-hour (hh:mm:ss)
  1250.  
  1251. `X'
  1252.      locale's time representation (H:M:S)
  1253.  
  1254. `c'
  1255.      locale's date and time (Sat Nov 04 12:02:33 EST 1989)
  1256.  
  1257. `D'
  1258.      date (mm/dd/yy)
  1259.  
  1260. `x'
  1261.      locale's date representation (mm/dd/yy)
  1262.  
  1263. 
  1264. File: find.info,  Node: Run Commands,  Next: Adding Tests,  Prev: Print File Information,  Up: Actions
  1265.  
  1266. Run Commands
  1267. ============
  1268.  
  1269.    You can use the list of file names created by `find' or `locate' as
  1270. arguments to other commands.  In this way you can perform arbitrary
  1271. actions on the files.
  1272.  
  1273. * Menu:
  1274.  
  1275. * Single File::
  1276. * Multiple Files::
  1277. * Querying::
  1278.  
  1279. 
  1280. File: find.info,  Node: Single File,  Next: Multiple Files,  Up: Run Commands
  1281.  
  1282. Single File
  1283. -----------
  1284.  
  1285.    Here is how to run a command on one file at a time.
  1286.  
  1287.  - Action: -exec COMMAND ;
  1288.      Execute COMMAND; true if 0 status is returned.  `find' takes all
  1289.      arguments after `-exec' to be part of the command until an
  1290.      argument consisting of `;' is reached.  It replaces the string
  1291.      `{}' by the current file name being processed everywhere it occurs
  1292.      in the command.  Both of these constructions need to be escaped
  1293.      (with a `\') or quoted to protect them from expansion by the shell.
  1294.      The command is executed in the directory in which `find' was run.
  1295.  
  1296.      For example, to compare each C header file in the current
  1297.      directory with the file `/tmp/master':
  1298.  
  1299.           find . -name '*.h' -exec diff -u '{}' /tmp/master ';'
  1300.  
  1301. 
  1302. File: find.info,  Node: Multiple Files,  Next: Querying,  Prev: Single File,  Up: Run Commands
  1303.  
  1304. Multiple Files
  1305. --------------
  1306.  
  1307.    Sometimes you need to process files alone.  But when you don't, it
  1308. is faster to run a command on as many files as possible at a time,
  1309. rather than once per file.  Doing this saves on the time it takes to
  1310. start up the command each time.
  1311.  
  1312.    To run a command on more than one file at once, use the `xargs'
  1313. command, which is invoked like this:
  1314.  
  1315.      xargs [OPTION...] [COMMAND [INITIAL-ARGUMENTS]]
  1316.  
  1317.    `xargs' reads arguments from the standard input, delimited by blanks
  1318. (which can be protected with double or single quotes or a backslash) or
  1319. newlines.  It executes the COMMAND (default is `/bin/echo') one or more
  1320. times with any INITIAL-ARGUMENTS followed by arguments read from
  1321. standard input.  Blank lines on the standard input are ignored.
  1322.  
  1323.    Instead of blank-delimited names, it is safer to use `find -print0'
  1324. or `find -fprint0' and process the output by giving the `-0' or
  1325. `--null' option to GNU `xargs', GNU `tar', GNU `cpio', or `perl'.
  1326.  
  1327.    You can use shell command substitution (backquotes) to process a
  1328. list of arguments, like this:
  1329.  
  1330.      grep -l sprintf `find $HOME -name '*.c' -print`
  1331.  
  1332.    However, that method produces an error if the length of the `.c'
  1333. file names exceeds the operating system's command-line length limit.
  1334. `xargs' avoids that problem by running the command as many times as
  1335. necessary without exceeding the limit:
  1336.  
  1337.      find $HOME -name '*.c' -print | grep -l sprintf
  1338.  
  1339.    However, if the command needs to have its standard input be a
  1340. terminal (`less', for example), you have to use the shell command
  1341. substitution method.
  1342.  
  1343. * Menu:
  1344.  
  1345. * Unsafe File Name Handling::
  1346. * Safe File Name Handling::
  1347. * Limiting Command Size::
  1348. * Interspersing File Names::
  1349.  
  1350. 
  1351. File: find.info,  Node: Unsafe File Name Handling,  Next: Safe File Name Handling,  Up: Multiple Files
  1352.  
  1353. Unsafe File Name Handling
  1354. .........................
  1355.  
  1356.    Because file names can contain quotes, backslashes, blank characters,
  1357. and even newlines, it is not safe to process them using `xargs' in its
  1358. default mode of operation.  But since most files' names do not contain
  1359. blanks, this problem occurs only infrequently.  If you are only
  1360. searching through files that you know have safe names, then you need not
  1361. be concerned about it.
  1362.  
  1363.    In many applications, if `xargs' botches processing a file because
  1364. its name contains special characters, some data might be lost.  The
  1365. importance of this problem depends on the importance of the data and
  1366. whether anyone notices the loss soon enough to correct it.  However,
  1367. here is an extreme example of the problems that using blank-delimited
  1368. names can cause.  If the following command is run daily from `cron',
  1369. then any user can remove any file on the system:
  1370.  
  1371.      find / -name '#*' -atime +7 -print | xargs rm
  1372.  
  1373.    For example, you could do something like this:
  1374.  
  1375.      eg$ echo > '#
  1376.      vmunix'
  1377.  
  1378. and then `cron' would delete `/vmunix', if it ran `xargs' with `/' as
  1379. its current directory.
  1380.  
  1381.    To delete other files, for example `/u/joeuser/.plan', you could do
  1382. this:
  1383.  
  1384.      eg$ mkdir '#
  1385.      '
  1386.      eg$ cd '#
  1387.      '
  1388.      eg$ mkdir u u/joeuser u/joeuser/.plan'
  1389.      '
  1390.      eg$ echo > u/joeuser/.plan'
  1391.      /#foo'
  1392.      eg$ cd ..
  1393.      eg$ find . -name '#*' -print | xargs echo
  1394.      ./# ./# /u/joeuser/.plan /#foo
  1395.  
  1396. 
  1397. File: find.info,  Node: Safe File Name Handling,  Next: Limiting Command Size,  Prev: Unsafe File Name Handling,  Up: Multiple Files
  1398.  
  1399. Safe File Name Handling
  1400. .......................
  1401.  
  1402.    Here is how to make `find' output file names so that they can be
  1403. used by other programs without being mangled or misinterpreted.  You can
  1404. process file names generated this way by giving the `-0' or `--null'
  1405. option to GNU `xargs', GNU `tar', GNU `cpio', or `perl'.
  1406.  
  1407.  - Action: -print0
  1408.      True; print the full file name on the standard output, followed by
  1409.      a null character.
  1410.  
  1411.  - Action: -fprint0 FILE
  1412.      True; like `-print0' but write to FILE like `-fprint' (*note Print
  1413.      File Name::.).
  1414.  
  1415. 
  1416. File: find.info,  Node: Limiting Command Size,  Next: Interspersing File Names,  Prev: Safe File Name Handling,  Up: Multiple Files
  1417.  
  1418. Limiting Command Size
  1419. .....................
  1420.  
  1421.    `xargs' gives you control over how many arguments it passes to the
  1422. command each time it executes it.  By default, it uses up to `ARG_MAX'
  1423. - 2k, or 20k, whichever is smaller, characters per command.  It uses as
  1424. many lines and arguments as fit within that limit.  The following
  1425. options modify those values.
  1426.  
  1427. `--no-run-if-empty'
  1428. `-r'
  1429.      If the standard input does not contain any nonblanks, do not run
  1430.      the command.  By default, the command is run once even if there is
  1431.      no input.
  1432.  
  1433. `--max-lines[=MAX-LINES]'
  1434. `-l[MAX-LINES]'
  1435.      Use at most MAX-LINES nonblank input lines per command line;
  1436.      MAX-LINES defaults to 1 if omitted.  Trailing blanks cause an
  1437.      input line to be logically continued on the next input line, for
  1438.      the purpose of counting the lines.  Implies `-x'.
  1439.  
  1440. `--max-args=MAX-ARGS'
  1441. `-n MAX-ARGS'
  1442.      Use at most MAX-ARGS arguments per command line.  Fewer than
  1443.      MAX-ARGS arguments will be used if the size (see the `-s' option)
  1444.      is exceeded, unless the `-x' option is given, in which case
  1445.      `xargs' will exit.
  1446.  
  1447. `--max-chars=MAX-CHARS'
  1448. `-s MAX-CHARS'
  1449.      Use at most MAX-CHARS characters per command line, including the
  1450.      command and initial arguments and the terminating nulls at the
  1451.      ends of the argument strings.
  1452.  
  1453. `--max-procs=MAX-PROCS'
  1454. `-P MAX-PROCS'
  1455.      Run up to MAX-PROCS processes at a time; the default is 1.  If
  1456.      MAX-PROCS is 0, `xargs' will run as many processes as possible at
  1457.      a time.  Use the `-n', `-s', or `-l' option with `-P'; otherwise
  1458.      chances are that the command will be run only once.
  1459.  
  1460. 
  1461. File: find.info,  Node: Interspersing File Names,  Prev: Limiting Command Size,  Up: Multiple Files
  1462.  
  1463. Interspersing File Names
  1464. ........................
  1465.  
  1466.    `xargs' can insert the name of the file it is processing between
  1467. arguments you give for the command.  Unless you also give options to
  1468. limit the command size (*note Limiting Command Size::.), this mode of
  1469. operation is equivalent to `find -exec' (*note Single File::.).
  1470.  
  1471. `--replace[=REPLACE-STR]'
  1472. `-i[REPLACE-STR]'
  1473.      Replace occurences of REPLACE-STR in the initial arguments with
  1474.      names read from standard input.  Also, unquoted blanks do not
  1475.      terminate arguments.  If REPLACE-STR is omitted, it defaults to
  1476.      `{}' (like for `find -exec').  Implies `-x' and `-l 1'.  As an
  1477.      example, to sort each file the `bills' directory, leaving the
  1478.      output in that file name with `.sorted' appended, you could do:
  1479.  
  1480.           find bills -type f | xargs -iXX sort -o XX.sorted XX
  1481.  
  1482.      The equivalent command using `find -exec' is:
  1483.  
  1484.           find bills -type f -exec sort -o '{}.sorted' '{}' ';'
  1485.  
  1486. 
  1487. File: find.info,  Node: Querying,  Prev: Multiple Files,  Up: Run Commands
  1488.  
  1489. Querying
  1490. --------
  1491.  
  1492.    To ask the user whether to execute a command on a single file, you
  1493. can use the `find' primary `-ok' instead of `-exec':
  1494.  
  1495.  - Action: -ok COMMAND ;
  1496.      Like `-exec' (*note Single File::.), but ask the user first (on
  1497.      the standard input); if the response does not start with `y' or
  1498.      `Y', do not run the command, and return false.
  1499.  
  1500.    When processing multiple files with a single command, to query the
  1501. user you give `xargs' the following option.  When using this option, you
  1502. might find it useful to control the number of files processed per
  1503. invocation of the command (*note Limiting Command Size::.).
  1504.  
  1505. `--interactive'
  1506. `-p'
  1507.      Prompt the user about whether to run each command line and read a
  1508.      line from the terminal.  Only run the command line if the response
  1509.      starts with `y' or `Y'.  Implies `-t'.
  1510.  
  1511. 
  1512. File: find.info,  Node: Adding Tests,  Prev: Run Commands,  Up: Actions
  1513.  
  1514. Adding Tests
  1515. ============
  1516.  
  1517.    You can test for file attributes that none of the `find' builtin
  1518. tests check.  To do this, use `xargs' to run a program that filters a
  1519. list of files printed by `find'.  If possible, use `find' builtin tests
  1520. to pare down the list, so the program run by `xargs' has less work to
  1521. do.  The tests builtin to `find' will likely run faster than tests that
  1522. other programs perform.
  1523.  
  1524.    For example, here is a way to print the names of all of the
  1525. unstripped binaries in the `/usr/local' directory tree.  Builtin tests
  1526. avoid running `file' on files that are not regular files or are not
  1527. executable.
  1528.  
  1529.      find /usr/local -type f -perm +a=x | xargs file |
  1530.        grep 'not stripped' | cut -d: -f1
  1531.  
  1532. The `cut' program removes everything after the file name from the
  1533. output of `file'.
  1534.  
  1535.    If you want to place a special test somewhere in the middle of a
  1536. `find' expression, you can use `-exec' to run a program that performs
  1537. the test.  Because `-exec' evaluates to the exit status of the executed
  1538. program, you can write a program (which can be a shell script) that
  1539. tests for a special attribute and make it exit with a true (zero) or
  1540. false (non-zero) status.  It is a good idea to place such a special
  1541. test *after* the builtin tests, because it starts a new process which
  1542. could be avoided if a builtin test evaluates to false.  Use this method
  1543. only when `xargs' is not flexible enough, because starting one or more
  1544. new processes to test each file is slower than using `xargs' to start
  1545. one process that tests many files.
  1546.  
  1547.    Here is a shell script called `unstripped' that checks whether its
  1548. argument is an unstripped binary file:
  1549.  
  1550.      #!/bin/sh
  1551.      file $1 | grep 'not stripped' > /dev/null
  1552.  
  1553.    This script relies on the fact that the shell exits with the status
  1554. of the last program it executed, in this case `grep'.  `grep' exits
  1555. with a true status if it found any matches, false if not.  Here is an
  1556. example of using the script (assuming it is in your search path).  It
  1557. lists the stripped executables in the file `sbins' and the unstripped
  1558. ones in `ubins'.
  1559.  
  1560.      find /usr/local -type f -perm +a=x \
  1561.        \( -exec unstripped '{}' \; -fprint ubins -o -fprint sbins \)
  1562.  
  1563. 
  1564. File: find.info,  Node: Common Tasks,  Next: Databases,  Prev: Actions,  Up: Top
  1565.  
  1566. Common Tasks
  1567. ************
  1568.  
  1569.    The sections that follow contain some extended examples that both
  1570. give a good idea of the power of these programs, and show you how to
  1571. solve common real-world problems.
  1572.  
  1573. * Menu:
  1574.  
  1575. * Viewing And Editing::
  1576. * Archiving::
  1577. * Cleaning Up::
  1578. * Strange File Names::
  1579. * Fixing Permissions::
  1580. * Classifying Files::
  1581.  
  1582.